OracleAS Portal Developer Kit (PDK)
Portal Tools: Upgrading to Release 10.1.3.2.0 and later

Last Updated:	January 27, 2007
Status:	Production
Version:	PDK Release 2 (10.1.3.2.0 and later)

Introduction
New Install Type
Post-upgrade Steps
Testing the Upgrade
Troubleshooting

Introduction

Note: Starting with PDK 9.0.4.1.0, the PDK download is intended to be installed and deployed in a standalone OC4J instance only. If you plan to use PDK in an Oracle Application Server instance, you must get and install the corresponding Oracle Application Server releases or patchsets.

This document contains information about how to upgrade your Portal Tools application from an earlier version of Portal Tools to the latest version. Since you are upgrading to 10.1.3.2 you will need a 10.1.3.x version of OC4J. Please refer to the Portal Tools Release Notes to find the minimum version. Then follow the steps indicated for the New Install type.

New Install Type

To install Portal Tools on a new Application Server, you first need to deploy the Portal Tools Application on the new Application Server, then restore the provider settings from the old Application Server:

Follow the steps described in the Deploying the PDK-Java portlet producers section of the Installing Portal Tools document.
Then follow the steps described in the Post-upgrade Steps section of this document.
Change the provider registration URLs in all of the clients (Portals or WebCenter applications) where you have registered your providers from the old Application Server to the new Application Server. You can typically do this in an Oracle Portal by clicking on Edit Registration for the provider name on the Providers tab of the Navigator, under Locally Built Providers or Registered Providers. Then click on the Connection tab and change the first part of the provider registration URL from:
http://<old_host>:<old_port>/...

to:

http://<new_host>:<new_port>/...

For example, change the OmniPortlet provider registration URL from:

http://<old_host>:<old_port>/portalTools/omniPortlet/providers/omniPortlet

to:

http://<new_host>:<new_port>/portalTools/omniPortlet/providers/omniPortlet

Change the URL for both OmniPortlet and Web Clipping providers.

Post-upgrade Steps

Restoring the Individual Providers Settings

Since redeploying the Portal Tools application overwrites your old provider settings, you'll need to restore the original individual provider settings. You only need to restore these settings for the providers you want to continue to use, and had configured before the upgrade. Before doing the restore, you should shut down the OC4J with the steps described in Shut Down your OC4J instance. The Portal Tools application contains the following providers:

Web Clipping Provider
OmniPortlet Provider

Note:

For New Install type, $BACKUPDIR refers to the old OC4J installation home.
If the PDK version you are upgrading from is not specified, you need to perform the step for all versions.

To Restore Web Clipping Provider Settings:

If Web Clipping was configured to use a proxy: copy the <proxyInfo> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml to the destination Oracle home.

The <proxyInfo> tag is a child of the <provider> tag and appears in the file following the <preferenceStore>...</preferenceStore> tag. The <proxyInfo> tag is shown in the example below.
```
<proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
   <httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
   <httpProxyPort>80</httpProxyPort>
</proxyInfo>
```

Copy the <repositoryInfo> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml to the destination Oracle home.

The <repositoryInfo> tag is a child of the <provider> tag and appears in the file following the <preferenceStore>...</preferenceStore> tag. The <repositoryInfo> tag is shown in the example below.

<repositoryInfo class="oracle.portal.wcs.provider.info.DatabaseInformation">
   <useRAA>false</useRAA>
   <databaseHost>mycompany.dbhost.com</databaseHost>
   <databasePort>1521</databasePort>
   <databaseSid>iasdb</databaseSid>
   <databaseUsername>webclip_user</databaseUsername>
   <databasePassword>AX3tR</databasePassword>
   <useASO>false</useASO>
</repositoryInfo>

If you had updated the <trustedCertificateLocation> tag information, copy it from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml to the destination Oracle home. Ensure the value points to a valid file location.
If you had manually added any portlet definitions to Web Clipping Provider's provider.xml file before upgrading, copy them to the destination Oracle home.
For PDK 9.0.2.4.0 only: After starting the instance, follow these steps to access the Web Clipping Provider Test Page:
1. Access the following URL:
  
  http://<host>:<port>/portalTools/webClipping/providers/webClipping
  
  The Web Clipping Provider Test page appears. If you have specified the same database for the Repository Target as that previously used for a PDK 9.0.2.4.0 installation, a Repository upgrade is also necessary. In this case, the Web Clipping Provider Test Page provides an Upgrade (from 9.0.2.4.0) link that you can click to perform installation of new tables and migration of existing Clipping Definitions to the latest versions.
  
  Note: If you perform the upgrade, the Clipping Definitions stored in the Web Clipping Repository will no longer work with PDK 9.0.2.4.0.
2. Click the Upgrade (from 9.0.2.4.0) link.
  
  Tables are added to the database schema hosting the Web Clipping repository, and all Definitions are upgraded.

To Restore the OmniPortlet Provider Settings :

For PDK 9.0.2.4.0 only: Copy the <useHashing>tag within the <preferenceStore> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home. If there is no <useHashing>tag in the source Oracle home, omit it in the destination Oracle home as well.

The <preferenceStore> tag is a child of the <provider> tag and appears in the file following the <session>...</session> tag. The <preferenceStore> tag is shown in the example below.
```
<preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
   <name>omniPortletprefStore</name>
   <useHashing>true</useHashing>
</preferenceStore>
```
If OmniPortlet was configured to use a proxy: Copy the <proxyInfo> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home.

The <proxyInfo> tag is a child of the <provider> tag and appears in the file following the <preferenceStore>...</preferenceStore> tag. The <proxyInfo> tag is shown in the example below.
```
<proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
   <httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
   <httpProxyPort>80</httpProxyPort>
</proxyInfo>
```
If you had updated the <trustedCertificateLocation> tag information, copy it from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home. Ensure the value points to a valid file location.
Update the <defaultLocale> and <localePersonalizationLevel> tags within the <portlet> tag.
For <defaultLocale> tag:
Copy the <defaultLocale> tag from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home. If there is no <defaultLocale>tag in the source Oracle home, enter the JVM default locale of the source instance as the value of the <defaultLocale> tag in the destination Oracle home. To find out what the JVM default locale is, you can alter the following statement in $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/htdocs/omniPortlet/TestPage.jspfrom:
<uix:globalHeader text="<%= pageTitle.toString() %>"/>
to:
<uix:globalHeader text="<%= pageTitle.toString() + \"+\" + java.util.Locale.getDefault() %>"/>
Then, bring up the OmniPortlet provider test page at:
http://<server>:<port>/portalTools/omniPortlet/providers/omniPortlet
Note the string in the banner. If it says: "Provider Test Page: omniPortlet+en", then the JVM default locale is "en".
Remember to undo your change above when done.

For <localePersonalizationLevel>tag:
Copy the old value from backed up provider.xml. If no old value in backed up provider.xml, simply set the value to locale. The tags are shown in the example below.
```
   <defaultLocale>en</defaultLocale>
   <localePersonalizationLevel>locale</localePersonalizationLevel>
```
Copy all directories under $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/to the destination Oracle home. This restores the customizations to the portlets you are using in OracleAS Portal from this provider.
If you had manually added any portlet definitions to OmniPortlet Provider's provider.xml file before upgrading, copy them to the destination Oracle home.
Configure the Secured data Repository as specified below. Ensure that you have copied the repositoryInfo tag information in the Web Clipping provider.xml as specified in the Web Clipping Settings above.
For PDK 9.0.2.4.0 only: After starting the instance, follow these steps to access the OmniPortlet Provider Test Page:
1. Access the following URL:
  
  http://<host>:<port>/portalTools/omniPortlet/providers/omniPortlet
  
  The OmniPortlet Provider Test page appears.
2. Click the Edit link adjacent to the status of the Secured Data Repository. In the Repository Settings section of the Edit Provider: webClipping page, the database connection information for Web Clipping Repository is shown.
3. Click OK to save the settings.
  
  The OmniPortlet's provider.xml file is updated with the correct <vaultId> tag to save secured data into the repository.
For PDK 9.0.2.6.2 only, if the OmniPortlet Secured Data Repository was configured: Copy the <vaultId> tag information from $BACKUPDIR/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml to the destination Oracle home.

The <vaultId> tag is a child of the <provider> tag and appears in the file following the <provider> tag. The <vaultId> tag resembles the following:

<vaultId>2</vaultId>

Configuring the Providers under Portal Tools

Now that Portal Tools is deployed and you have restored the individual provider settings, you can start the OC4J that you have previously shut down, so that you can configure the individual providers and begin using them in an OracleAS Portal instance. You can configure the providers from the Portal Tools home page:

http://server:port/portalTools

The home page lists the providers under Portal Tools. Click each link to display the provider's test page and configure the provider.

Testing the Upgrade

After you have completed the above steps, you can test your upgraded Portal Tools application. First, access the Portal Tools home page at http://<host>:<port>/portalTools. This page lists the providers under the Portal Tools. Click any of these links to display a pre-configured provider test page. You can also verify that the portlets from earlier version of PortalTools are showing the expected results on the portal pages where they had been already put. Refer to the Troubleshooting section if an unexpected behavior occurs.

Troubleshooting After the Upgrade

This section contains information on resolving issues you may encounter after the upgrade.

When you view a page containing an OmniPortlet or Simple Parameter Form portlet, you see a "Define the portlet" link.

Cause: The user has added an OmniPortlet or Simple Parameter Form portlet from PDK 9.0.2.4.0 and has not yet customized it.
Action: Click the Define the portlet link and customize the OmniPortlet definition.

An OmniPortlet that uses an XML or CSV data source now show errors.

Cause: Check the application.log for errors.
Action: If the data source files were referred from files in the OmniPortlet Web application, they were probably removed during the upgrade. Copy them back to the appropriate location(s) from $BACKUPDIR.

Portlet definitions you manually created in the previous version of the Portal Tools application now show errors.

Cause: These portlet definitions were probably not transferred to the new provider.xml.
Action: Copy the new portlet definitions to $INSTALL_HOME/j2ee/OC4J_Instance/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml.

You created portlet definitions for the previous version of OmniPortlet. When you add these portlets to a page, they display the "Define the portlet" link.

Cause: The new code base of OmniPortlet renders the "Define the portlet" link when the portlet is first dropped to page.
Action: After you define the portlet, the data is displayed onto the portlet. If you want to display pre-configured data in the newly dropped portlet, you need to put the following tag in provider.xml :

<showDefineLink>false</showDefineLink>

This tag should be put after end of <header> tag under <definition> tag under your portlet definition.

After upgrade, when you perform "edit defaults" on an upgraded instance of a portlet, you see <None> in the field(s) where you had chosen some column from data-source (before upgrade).

Cause: Either the name of the column you selected starts with a numeric character or it contains special character(s) other than alphanumeric character(s) and '_' (underscore) character. The special character(s) could be space, '%' etc. All instances of such special characters are replaced by '_' ( underscore) character. For example, if column name before upgrade was 'Department No', after upgrade it will be displayed as 'Department_No'.
Action: You need to select the (renamed) column again in all such cases.

Revision History:

Revision No	Last Update
1.0	June 30, 2003
1.1	September 15, 2003
2.0	November 17, 2003
2.4	December 7, 2004
3.0	June 23, 2005
4.0	January 27, 2007


Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/	Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200	Copyright and Corporate Info

OracleAS Portal Developer Kit (PDK) Portal Tools: Upgrading to Release 10.1.3.2.0 and later

Contents